在 kintone 開發中，透過 REST API 操作記錄流程狀態是一個常見需求，尤其是自動化工作流程時。然而，在開發過程中可能會遇到執行【PUT】/k/v1/record/status.json 時出現「無權限」、「非執行者」等錯誤。本文將探討這些錯誤的成因以及解決方法，並提供權限設定的建議。

REST API 更新記錄流程狀態的權限要求

kintone 提供的【PUT】/k/v1/record/status.json API 用於更新記錄的流程狀態。在呼叫此 API 時，必須滿足以下基本權限要求：

• 執行 API 之使用者，需具備對象記錄的閱覽權限。

而根據執行 API 時的認證方式不同，還會有以下限制：

1. 透過使用者認證執行 API
   • 執行 API 的使用者必須是當前流程狀態的執行者，或該流程狀態未指定執行者。
2. 透過 API token 認證執行 API
   • 執行 API 時，當前流程狀態的執行者必須是「Administrator」，或該流程狀態未指定執行者。

開發者最常遇到的問題是：「我明明使用 API token 認證執行 API，怎麼還會沒有權限？」就是因為上面第二點的限制。簡單來說，即便是使用 REST API 更新流程，除非沒有指定執行者，否則操作者也必須是執行者，而透過 API token 認證時的操作者則視為 Administrator。因此，在未做額外處理的情況下，仍需確認執行者身份。

權限問題的解決方案

原則上，遵循僅有執行者可以執行流程動作的規則是比較合乎邏輯的，但若有必要，仍可透過「修改執行者」的方式來解決權限不足的問題。

在執行狀態更新的 API 前，先執行更新執行者的 API： 【PUT】/k/v1/record/assignees.json，使操作者的權限符合需求。

由於執行此 API 需要有應用程式管理權限，較方便的做法是使用 kintoneRestAPIClient ，以 API token 認證（需授予：查看記錄、應用程式管理）進行操作。範例程式碼如下：

// 使用 API token 認證
const tokenClient = new KintoneRestAPIClient({
  auth: {
    apiToken: 'YOUR_APP_API_TOKEN'
  }
});

// 不帶 auth 參數時，使用登入使用者認證（Session authentication）
const userClient = new KintoneRestAPIClient();

// 更新執行者
await tokenClient.record.updateRecordAssignees({
  app: kintone.app.getId(), // 應用程式ID
  id: '指定記錄ID',
  assignees: [] // 更改執行者
});

// 更新流程狀態
await userClient.record.updateRecordStatus({
  app: kintone.app.getId(),
  id: '指定記錄ID',
  action: '欲執行的動作名稱'
});

參數 assignees 為一陣列，內含執行者的使用者代號（code）。由於只要該狀態未指定執行者時，操作者只需擁有記錄的閱覽權限即可執行，因此直接清除指定執行者是最簡單、最通用的方式，只要將 assignees 設為空陣列即可。

清除指定執行者後再使用 API 更新流程狀態時，狀態履歷上的動作執行者將依驗證方式而定：

• 使用者認證：執行者為該使用者。
• API token 認證：執行者為 Administrator。

特殊情境注意事項

若流程動作按鈕出現的條件與使用者綁定，例如：

設定了「Administrator」為指定執行者的動作「復原」，若使用上述方式清除執行者再更新流程狀態，會發生以下錯誤：

await tokenClient.record.updateRecordAssignees({
  app: kintone.app.getId(),
  id: '指定記錄ID',
  assignees: []
});

await tokenClient.record.updateRecordStatus({
  app: kintone.app.getId(),
  id: '指定記錄ID',
  action: '復原'
});

錯誤訊息：

KintoneRestAPIError: [400] [GAIA_IL03] 狀態變更失敗。
可能有其他使用者變更了狀態或狀態的設定。 (PWcmHG5YX7vgZu6EtEHe)

發生錯誤的原因是，在執行狀態更新之前執行者已被清空，導致沒有「復原」這個動作可以執行。這點也是在實際應用上需要特別留意的地方。

結語

在使用 kintone REST API 自動化流程時，理解 API 的權限要求能有效避免執行錯誤。若需在流程中切換執行者，可透過 [PUT] /k/v1/record/assignees.json 清除或指定執行者，確保流程能順利執行。最後，請謹慎管理 API token 權限，避免不必要的安全風險。